HAL HASH types migration

This section provides information about the HAL HASH types migration.

HAL HASH callback ID type definition

HAL1

HAL2 

typedef enum
{
  HAL_HASH_DGSTCPLT_CB_ID,
  HAL_HASH_ERROR_CB_ID,
  HAL_HASH_INPUTCPLT_CB_ID,
  HAL_HASH_MSPDEINIT_CB_ID,
  HAL_HASH_MSPINIT_CB_ID,
} HAL_HASH_CallbackIDTypeDef;

  • Removed from HAL2 : the callback registration is managed by dedicated functions for each HASH event. See HAL HASH callbacks register functions for more details.

  • HAL_HASH_MSPINIT_CB_ID and HAL_HASH_MSPDEINIT_CB_ID are removed because the functions HAL_HASH_MspInit() and HAL_HASH_MspDeInit() are removed.

Related concepts:

HAL HASH processing phases type definition

HAL1

HAL2 

typedef enum
{
  HAL_HASH_PHASE_HMAC_STEP_1,
  HAL_HASH_PHASE_HMAC_STEP_2,
  HAL_HASH_PHASE_HMAC_STEP_3,
  HAL_HASH_PHASE_PROCESS,
  HAL_HASH_PHASE_READY,
} HAL_HASH_PhaseTypeDef;

Removed : In HAL2, the hash process phase is not needed for the user, it is used only in the internal implementation.

HAL HASH state type definition

HAL1

HAL2 

typedef enum
{
  HAL_HASH_STATE_RESET,
  HAL_HASH_STATE_READY,

  HAL_HASH_STATE_BUSY,
  HAL_HASH_STATE_SUSPENDED,
  HAL_HASH_STATE_ERROR,
  HAL_HASH_STATE_TIMEOUT,

} HAL_HASH_StateTypeDef;

typedef enum
{
  HAL_HASH_STATE_RESET               ,
  HAL_HASH_STATE_INIT                ,
  HAL_HASH_STATE_CONFIGURED          ,
  HAL_HASH_HMAC_STATE_CONFIGURED     ,
  HAL_HASH_STATE_COMPUTE_ACTIVE      ,
  HAL_HASH_STATE_UPDATE_ACTIVE       ,
  HAL_HASH_HMAC_STATE_COMPUTE_ACTIVE ,
  HAL_HASH_HMAC_STATE_UPDATE_ACTIVE  ,
  HAL_HASH_STATE_SUSPENDED           ,
  HAL_HASH_STATE_ABORT
} hal_hash_state_t;

Related concept: Revised and optimized HAL state machine

HAL HASH suspend type definition

HAL1

HAL2 

typedef enum
{
  HAL_HASH_SUSPEND_NONE,
  HAL_HASH_SUSPEND,
} HAL_HASH_SuspendTypeDef;

Removed : In HAL2, the hash suspend is not needed for the user, it is used only in the internal implementation.

HAL HASH configuration type definition

HAL1

HAL2

In HAL1, there is a single structure called HASH_ConfigTypeDef that handles both HASH and HMAC configurations. For HASH operation, only the data type and algorithm parameters are configured, while for HMAC, the key pointer and key size are also included in the same structure. 

typedef struct
{
   uint32_t DataType;
   uint32_t Algorithm;
   uint8_t *pKey;     /* used only for HMAC operation */
   uint32_t KeySize;  /* used only for HMAC operation */
} HASH_ConfigTypeDef;

In HAL2, the configuration is split into two distinct structures: one dedicated to HASH configuration hal_hash_config_t, and another specifically for HMAC hal_hash_hmac_config_t, which includes the key and key size parameters. 

typedef struct
{
   hal_hash_data_swapping_t data_swapping;
   hal_hash_algo_t          algorithm;
   uint8_t                  *p_key;
   uint32_t                 key_size_byte;
} hal_hash_hmac_config_t;

typedef struct
{
   hal_hash_data_swapping_t data_swapping;
   hal_hash_algo_t          algorithm;
} hal_hash_config_t;

Usage example: 

/* This example is used with STM23H5 */
static const uint8_t pKeyHASH[261] __ALIGN_END = {
                    0x54,0x68,0x65,0x20,0x68,0x61,0x73,0x68,0x20,0x70,
                    ...........,
                    ...........,
                    0x2a,0x20,0x53,0x54,0x4d,0x33,0x32,0x20,0x2a,0x2a};
/* Set HASH parameters  for HMAC operation */
HASH_ConfigTypeDef config;
config.DataType   = HASH_BYTE_SWAP;
config.pKey       = (uint8_t *)pKeyHASH;
config.Algorithm  = HASH_ALGOSELECTION_SHA512;
config.KeySize    = 261;
 HAL_HASH_SetConfig(&hhash, &config);

Usage example: 

/* This example is used with STM23H5 */
static const uint8_t pKeyHASH[261] __ALIGN_END = {
                    0x54,0x68,0x65,0x20,0x68,0x61,0x73,0x68,0x20,0x70,
                    ...........,
                    ...........,
                    0x2a,0x20,0x53,0x54,0x4d,0x33,0x32,0x20,0x2a,0x2a};
 /* Set HASH parameters  for HMAC operation */
 hal_hash_hmac_config_t hash_hmac_cfg;
 hash_hmac_cfg.data_swapping  = HAL_HASH_DATA_SWAP_BYTE;
 hash_hmac_cfg.algorithm = HAL_HASH_ALGO_SHA512;
 hash_hmac_cfg.p_key = (uint8_t *)pKeyHASH;
 hash_hmac_cfg.key_size_byte=261;
 HAL_HASH_HMAC_SetConfig(&hhash, &hash_hmac_cfg);

Note

This structure is used in only some devices.

Related concepts:

HAL HASH handle type definition

HAL1

HAL2 

HASH_HandleTypeDef;

hal_hash_handle_t;

Related concept: Renaming of the handle structure

HAL HASH initialization type definition

HAL1

HAL2

In HAL1, a single structure HASH_InitTypeDef is used to configure both HASH and HMAC operations.

  • For HASH operation, only the data type is configured.

  • For HMAC operation, the key pointer and key size are also included in the same structure.

HAL1 provides dedicated functions for specific algorithms sush as HAL_HASH_SHA1_Start() that implicitly set the algorithm internally.

In HAL2, the init structure is removed and two distinct structures for HASH configuration and HMAC configuration are provided.

  • For HASH operation, the hal_hash_config_t structure configures data type and the dedicated algorithm to the processing function

  • For HMAC operation, the hal_hash_hmac_config_t structure extends the HASH configuration by including the key and key size.

 
typedef struct
{
   uint32_t DataType;

   uint8_t *pKey;     /* used only for HMAC operation */
   uint32_t KeySize;  /* used only for HMAC operation */
} HASH_InitTypeDef;

typedef struct
{
   hal_hash_data_swapping_t data_swapping;
   hal_hash_algo_t          algorithm;
   uint8_t                  *p_key;
   uint32_t                 key_size_byte;
} hal_hash_hmac_config_t;

typedef struct
{
   hal_hash_data_swapping_t data_swapping;
   hal_hash_algo_t          algorithm;
} hal_hash_config_t;

HAL HASH callback type definition

HAL1

HAL2 

pHASH_CallbackTypeDef

hal_hash_cb_t

Related concept: Replaced TypeDef suffix with _t in type names